This document describes how to set up a development environment for bexee. In fact it describes how to reproduce the development environment that we have used during development. It is meant to simplify the setup process and get you up and running as fast as possible without having to go through the hassle of experimenting with different configurations that might not work. You are certainly not forced to use the mentioned tools, e.g. you are free to use any SSH client of your personal choice, but we can not guarantee that everything will work properly, so we recommend that you follow the instructions in this document.
It is assumed that you have checked out the sources from CVS and are more or
less familiar with the tools referred to in this document.
The examples used in this document are Windows specific. You should be able
to set up a similar environment on a Unix-based machine.
Download and install Maven 1.0 from the Apache Maven Project Site [Maven].
After installing Maven make sure that the MAVEN_HOME
environment variable is set and points to the location where you have
installed maven:
MAVEN_HOME=c:\java\maven
If you install Maven on a Windows machine, make sure that you set
MAVEN_HOME as a system variable (not user variable).
Add %MAVEN_HOME%\bin to your path so you can execute it
from any location within a shell:
Path=...;%MAVEN_HOME%\bin
Next, create your local repository by running the following commands:
%MAVEN_HOME%\bin\install_repo.bat %USERPROFILE%\.maven\repository
Everything in Maven gravitates around the definition of a project. The unit of work in Maven is the project, so before you can get started with Maven you need to adapt the project definition to your environment.
This particularly means that you might need to make slight adjustments
to the project.xml e.g. changing the information on
how to access your CVS and web server
Change to the bexee directory (that is where you checked out the
sources from CVS). Copy build.properties to your user
home directory. Don't worry about modifying it right now. We will
explain how to set the values in section SSH Access to
Web Site.
Below you see a sample file:
maven.username=patforna
maven.ssh.executable=plink
maven.scp.executable=pscp
maven.ssh.args=-A -ssh -2 -i ${user.home}/sf-shell.ppk
maven.scp.args=-2 -i ${user.home}/sf-shell.ppk
maven.tomcat.username=admin
maven.tomcat.password=
In order to be able to deploy the web site via SSH to the web server, you'll have to obtain an SSH client. We used PuTTY [PuTTY]in our environment, since it comes with all the functionality we need and is free.
In fact, all you need is three programs called PSCP, Plink and PuTTYgen.
Copy the binaries into a directory that is on your path (e.g. into your
windows\system32 directory). This way you can execute the
programs from anywhere without specifying their absolute location.
Execute PUTTYGEN.EXE
Select the desired key type ("SSH2 DSA", within the "Parameters" section).
Click on the "Generate" button.
Follow the on-screen instructions ("Please generate some randomness by moving the mouse over the blank area"). Key generation will be performed immediately afterward.
Enter username@shell.sf.net in the "Key comment" field, replacing 'username' with your SourceForge.net user name. This comment will help you to identify the purpose of this key. For the sake of simplicity leave the "Key passphrase" fields empty. This way you don't need other tools running in the background (like i.e. Pageant) which makes automatic deployment with Maven a lot easier, but you have to be aware that your private key will be saved as plain text.
Click on the "Save private key" button; use the resulting dialog to save your private key data for future use. You may use a filename such as "sourceforge.ppk" for example. The .ppk extension is used for PuTTY Private Key files. Save the private key in your user home directory.
Go to your Account Maintenance page on the SourceForge.net site and click on [Edit SSH Keys for Shell/CVS]. Copy your public key data from the "Public key for pasting into OpenSSH authorized_keys file" section of the PuTTY Key Generator and paste in to the provided form on the SourceForge.net site.
Exit the PuTTY Key Generator.
Use plink for example to manually connect to your web
server (the one you defined in project.xml) from a shell.
It's important that you do it manually the first time, as PuTTY will ask
you to store the host fingerprint (answer 'yes').
For more information about Using public key authentication with PuTTY, please refer Chapter 8: Using public keys for SSH authentication in the PuTTY user manual [PuTTYManual]
Now, let's try if everything has been set up correctly. Enter
maven site:deploy
Maven will first download all the required jars. This may take a couple of minutes because you most likely have not downloaded any of the required jars before.
To be able to deploy war files to Tomcat with Maven you first need to download the Codeczar Tomcat plugin [TomcatPlugin]. You can do this very easily with Maven by entering the following command:
maven -DartifactId=maven-tomcat-plugin -DgroupId=codeczar-tomcat -Dversion=1.1 plugin:download
Here is an excerpt of the goals that the plugin provides:
| tomcat:deploy | Deploys a web application from a war file. |
| tomcat:undeploy | Undeploys a deployed war file. |
| tomcat:install | Install a web application in expanded directory format. |
| tomcat:reload | Reload a web application in expanded directory format. |
| tomcat:remove | Remove a web application in expanded directory format. |
bexee is being developed as an Eclipse project which means that you can easily import and use it in your own Eclipse environment.
Foremost you have to define a new classpath variable called
MAVEN_REPO which points to your Maven repository directory.
Then select File -> Import. Choose 'Checkout Projects from CVS'.
Enter information on how to access CVS.
Select 'Use an existing module' and browse for the bexee module.
Select 'Check out as project in workspace' and use bexee as project name.
Finally enter the path where you want to check out the project and click finish.
Eclipse will now probably complain that not all folders on the build path
are present or not all the necessary libraries have been downloaded by
maven yet. You can solve this problem by running maven site
in a shell, which will create the necessary folders. After refreshing the
project in Eclipse everything should be ok.